________________________________________________________________________ Chapter 3: The Object Hierarchy 29 ________________________________________________________________________ CHAPTER THREE: THE OBJECT HIERARCHY Each handler, whose components were discussed in the preceding chapter, depends on receiving a specific message in order to execute its statements. This section describes HyperPAD's message passing system, how messages are sent to objects and what happens when the messages are received by objects. The type and nature of the message and the current object at the time the message was generated determines which object receives the message first. The receiving object may or may not have a handler for that message. If it does, then the handler for that message executes and the message stops its travel. If the object does not have a handler for that message, then the message is passed on to the next object in the hierarchy. This process continues until there is either a handler for that message or the message reaches HyperPAD. The types of messages and the path that the messages take during their travel through HyperPAD (the hierarchy) are discussed in this chapter. ________________________________________________________________________ Chapter 3: The Object Hierarchy 30 ________________________________________________________________________ SENDING MESSAGES Within HyperPAD, script execution is initiated by messages sent to objects. Messages are HyperPAD's way of "telling" the objects what's taking place in the environment. Messages are sent: 0 When an event occurs (like a key being pressed or mouse button being clicked). 0 When the user executes a statement from the message box. 0 When certain commands are executed from within a script, such as: beep. 0 When the user selects a menu command. 0 When the system is idle. WHERE DO MESSAGES GO? When an object receives a message, one of two actions is taken. If the object has a handler for that message, the handler is executed and the message travel is stopped. If the object doesn't have a handler for the message, then the message is sent to the next object in the object hierarchy. The message will continue along in this manner until it encounters a handler for itself, or reaches HyperPAD. The following diagram summarizes the path taken by a message through HyperPAD: ________________________________________________________________________ Chapter 3: The Object Hierarchy 31 ________________________________________________________________________ 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � **** The Printed Documentation has a picture or screen shot here **** � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� ________________________________________________________________________ Chapter 3: The Object Hierarchy 32 ________________________________________________________________________ The object with the focus receives the message first, which will usually be either a page, button, or field. For example, if a button is highlighted and the user selects it (by pressing ENTER) a select message is sent to the button. If the script doesn't have a select handler, the message is sent to the page, and on up the hierarchy until a handler is found or the message reaches HyperPAD. If the message reaches HyperPAD, one of three actions is taken. 1. The message will be ignored. This happens when there is no handler for a system message. 2. The message will be interpreted by HyperPAD. This happens, for example, with the quit message. 3. An error will be displayed indicating that HyperPAD didn't understand the message. TYPES OF MESSAGES The types of messages that are sent are discussed in this section. SYSTEM MESSAGES The most common messages passed through HyperPAD are system messages. These messages are sent to an object in response to a user-generated event. For example, if the pad user presses the left mouse button, the mouseDown message is sent to the object under the mouse pointer. Because system messages are generated by the pad user, the messages are initially sent to either the current page, button, or field. The object that first receives the message is called the target. There are two types of system messages: 1. Notification messages. These are messages that result from an action in the system and whose purpose is to notify a script that an action has occurred. Some examples are: openPage, mouseUp, newPad Creating handlers for these messages lets you specify actions to be performed after the user has completed an action in HyperPAD. For example, a mouseUp handler can be used to trigger some actions after the mouse button has been physically released. 2. Normal messages. These messages are sent before any actions have been taken and result in an action occurring when the message reaches HyperPAD. Normal messages are those that HyperPAD understands, such as doMenu, quit, help, beep, and deletePage. For example, if you select ________________________________________________________________________ Chapter 3: The Object Hierarchy 33 ________________________________________________________________________ Delete Button on the Edit menu, then the deleteButton command is sent to that button. Only when this message is received by HyperPAD will the button be deleted. By creating handlers for these messages, you can control different aspects of HyperPAD. For example, the following handler intercepts the quit message asking if it is ok to quit. If the user selects Ok, the handler passes the message on (so that it will reach HyperPAD and you'll exit to DOS). If not, the message stops and HyperPAD doesn't quit. handler select; begin answer "Ok to quit?"; if it is "Ok" then pass; end; MESSAGES FROM SCRIPTS Within your scripts, you can send messages. For example: handler select; begin CalculateResult; end; The message calculateResult will be sent to the script of the currently executing object. If there is a handler called calculateResult somewhere in the message path, it will then be executed. MESSAGE BOX MESSAGES The message box provides a way of executing statements immediately without having to type in a script. When you type in a command and press ENTER, one of the following will occur: 1. If you typed in a command, it will be executed (except the do command and any begin...end block). 2. If you typed in a message and parameters, the message will be sent to the current page. If there is a handler for the message, it will be executed. If there is no handler, and HyperPAD doesn't recognize the message, an error is displayed. 3. If a valid expression was entered, it is evaluated and the result is placed into the message box. ________________________________________________________________________ Chapter 3: The Object Hierarchy 34 ________________________________________________________________________ MESSAGES THAT LOOK LIKE COMMANDS Some commands within scripts are implemented as messages. This may seem confusing. For example, you may, at first, be unable to determine if the following statement is a command or a message: beep; In fact, this is a command that sends a message called beep. When this message reaches HyperPAD, a sound is emitted from the system speaker. All of these special messages are noted in the Chapter Ten. RECEIVING AND SENDING MESSAGES As you learned above, the initial receiver of a message depends on the type and nature of the message as well as which object is currently selected when the message is generated. As senders and receivers of messages, all objects work the same. The type of object has no effect on the execution of the script. The following outlines the procedure taken when an object receives a message: First, the script is searched for a handler that corresponds to the message. If a match is located, that specific handler is executed. After a handler executes, the message stops its travel up the hierarchy unless it is passed with the pass command. If no matches are found, the message is passed to the next object up the hierarchy. ________________________________________________________________________ Chapter 3: The Object Hierarchy 35 ________________________________________________________________________ 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � **** The Printed Documentation has a picture or screen shot here **** � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� THE EXIT COMMAND The exit command stops execution of a handler before the last statement of the handler has executed. In the following example, the statements following the exit statement will never be executed: handler select; begin exit; beep; go to the next page; end; The exit command terminates that message's travel through the hierarchy. If you want to stop the execution of all pending handlers, use the exit to hyperpad command. This command is similar to the user pressing CTRL+BREAK. ________________________________________________________________________ Chapter 3: The Object Hierarchy 36 ________________________________________________________________________ The following example uses the exit to hyperpad command to stop the display of a sequence of screens. The checkContinue handler below does this by stopping all pending handlers, including the calling handler, at the user's request. handler checkContinue; begin answer "Is it ok to continue?"; if it is "Cancel" then exit to hyperpad; end; handler select; begin go to the next page; checkContinue; go to the next page; checkContinue; go to pad "phone"; checkContinue; go home; end; THE PASS COMMAND The pass command enables a handler to send the message to the next object in the hierarchy, as if the current handler hadn't received it. For example, consider the following scripts: Script: Description: --------------------------------------------------------- handler select; This message will stop here, and begin will not go on to the next level in : the message path. end; handler select; This script intercepts the message, begin performs some actions, and then : passes the message on to be handled pass; by other objects higher in the end; hierarchy. ________________________________________________________________________ Chapter 3: The Object Hierarchy 37 ________________________________________________________________________ The pass command stops execution of a handler. For example, in the following script, the beep statement never gets executed: handler select; begin pass; beep; end; Make sure you position the pass statement as the last statement in the script you want executed. ALTERING THE MESSAGE PATH Messages are normally passed by default up the hierarchy, never across to other objects on the same level. With the send command, however, you can redirect messages to objects outside the normal hierarchy, such as those objects on another page, or lower in the hierarchy. For example, the following handler redirects the mouseUp message to a button on another page: handler mouseUp; begin send "mouseUp" to button "Help" of page 2; end; ________________________________________________________________________ Chapter 3: The Object Hierarchy 38 ________________________________________________________________________ If the receiving object does not contain a handler for that message, the message will proceed to travel up that object's hierarchy (not the hierarchy of the sending object). 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � **** The Printed Documentation has a picture or screen shot here **** � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� ________________________________________________________________________ Chapter 3: The Object Hierarchy 39 ________________________________________________________________________ Messages sent from a script travel up the path of that sending object. This is important to remember in cases like the following: handler mouseUp; begin go to pad "B"; calculateTotals; end; Even though the pad has been changed (to pad "B"), the message calculateTotals still travels the message path of the original pad. WHERE TO PUT YOUR HANDLERS Considering all of the stops a message makes on its journey along the message path, it may at first be difficult to decide where to put your handlers. For example, should you put a handler in the script of a button, a page script, the corresponding background script, the pad script, or maybe in the Home pad script? To answer this question, you need to determine which objects need to use this handler. Then you will know exactly where to locate your handlers. Simply put, your handlers should be located in the script of the object lowest in the hierarchy and still be accessible to all the objects that need that handler. For example, if you have a single button that, when selected, takes you to the next page, you would create a handler in the script of the button. Suppose that you have 10 buttons on the page and you want the pad user to be able to click on any button and go to the next page. Instead of including this handler in the script of each of the ten buttons, you could put the handler into the script of the page. Thus, all buttons on the page would respond to the select message using the same handler. (Remember that if an object doesn't have a handler for a message, it is passed on to the next layer...in this case, the page.) In the next case, suppose that you have a handler called calcResult that you would like to access from several different pages which are all on the same background. Instead of including the handler in each page script that requires it, you could put the handler in the background script, making it accessible to every page that uses that background. Next, suppose that the calcResult handler is used in many different pages, buttons and fields throughout your entire pad, even from different backgrounds. In this case, you would want to put the handler in the pad script, making it accessible to each object in the pad. ________________________________________________________________________ Chapter 3: The Object Hierarchy 40 ________________________________________________________________________ In the last case, suppose that the calcResult handler was used in many of your pads. Depending on how often it is used, you may want to copy it into each pad that uses it. Another approach is to put the handler in the pad script of the Home pad. This makes the handler accessible to all of your pads. You must be careful, however, to keep this script small and efficient because it is always loaded (thus requiring more memory).